DSAFEARRAY Class

DSAFEARRAY is a class that provides wrapper methods for the SAFEARRAY structure, making it easy to create and manage single- and multidimensional arrays of almost any of the VARIANT-supported types. The lower bound of a DSAFEARRAY can start at any user-defined value. Additional overloaded methods are provided for one and two-dimensional safe arrays, that are the ones most often used in COM programming.

When the class is destroyed, the array descriptor and all of the data in the array is destroyed. If objects are stored in the array, IUnknown_Release is called on each object in the array. Safe arrays of variants will have VariantClear called on each member and safe arrays of BSTR will have SysFreeString called on each element. IRecordInfo.RecordClear will be called to release object references and other values of a record without deallocating the record.

Include file: AfxNova/DSafeArray.inc.

Structures and VARTYPE

Constructors

Operators

Methods

Helper Procedures

SAFEARRAY Structure

Represents a safe array.

TYPE tagSAFEARRAY
   cDims as USHORT
   fFeatures as USHORT
   cbElements as ULONG
   cLocks as ULONG
   pvData as PVOID
   rgsabound(0 to 0) as SAFEARRAYBOUND
EBD TYPE

fFeatures Flags

Remarks

The array rgsabound is stored with the left-most dimension in rgsabound[0] and the right-most dimension in rgsabound(cDims - 1).

The fFeatures flags describe attributes of an array that can affect how the array is released. The fFeatures field describes what type of data is stored in the SAFEARRAY and how the array is allocated. This allows freeing the array without referencing its containing variant. The bits are accessed using the following constants:

Thread Safety

All public static members of the SAFEARRAY data type are thread safe. Instance members are not guaranteed to be thread safe.

For example, consider an application that uses the SafeArrayLock and SafeArrayUnlock functions. If these functions are called concurrently from different threads on the same SAFEARRAY data type instance, an inconsistent lock count may be created. This will eventually cause the SafeArrayUnlock function to return E_UNEXPECTED. You can prevent this by providing your own synchronization code.

SAFEARRAYBOUND Structure

Represents the bounds of one dimension of the array. The lower bound of the dimension is represented by lLbound, and cElements represents the number of elements in the dimension. The structure is defined as follows:

TYPE SAFEARRAYBOUND
   cElements as ULONG
   lLbound as LONG
END TYPE

Safe array Variant type

The base type of the array (the VARTYPE of each element of the array). The VARTYPE is restricted to a subset of the variant types. Neither the VT_ARRAY nor the VT_BYREF flag can be set. VT_EMPTY and VT_NULL are not valid base types for the array. All other types are legal.

Constructor (SAFEARRAYBOUND)

Creates a DSAFEARRAY.

Multidimensional array:

CONSTRUCTOR DSAFEARRAY (BYVAL vt AS VARTYPE, BYVAL cDims AS UINT, BYVAL prgsabounds AS SAFEARRAYBOUND PTR)
CONSTRUCTOR DSAFEARRAY (BYREF strType AS STRING, BYVAL cDims AS UINT, BYVAL prgsabounds AS SAFEARRAYBOUND PTR)

One-dimensional array:

CONSTRUCTOR DSAFEARRAY (BYVAL vt AS VARTYPE, BYVAL cElements AS ULONG = 0, BYVAL lLBound AS LONG = 0)
CONSTRUCTOR (BYREF strType AS STRING, BYVAL cElements AS ULONG = 0, BYVAL lLBound AS LONG = 0)

Two-dimensional array:

CONSTRUCTOR DSAFEARRAY (BYVAL vt AS VARTYPE, BYVAL cElements1 AS ULONG, BYVAL lLBound1 AS LONG, _
   BYVAL cElements2 AS ULONG, BYVAL lLBound2 AS LONG)
CONSTRUCTOR (BYREF strType AS STRING, BYVAL cElements1 AS ULONG, BYVAL lLBound1 AS LONG, _
   BYVAL cElements2 AS ULONG, BYVAL lLBound2 AS LONG)

Usage examples

' // Two-dimensional array of BSTR
' // 2D: elements = 5, lower bound = 1
' // 2D: elements = 3, lower bound = 1
DIM rgsabounds(0 TO 1) AS SAFEARRAYBOUND = {(5, 1), (3, 1)}
DIM dsa AS DSAFEARRAY = DSAFEARRAY(VT_BSTR, 2, @rgsabounds(0))
-or-
' // Two-dimensional array of BSTR
DIM dsa AS DSAFEARRAY = DSAFEARRAY(VT_BSTR, 5, 1, 3, 1)

' // One-dimensional array of VT_VARIANT with 0 elements and a lower-bound of 0
DIM dsa AS DSAFEARRAY = DSAFEARRAY(VT_VARIANT, 0, 0)
-or-
DIM dsa AS DSAFEARRAY = DSAFEARRAY(VT_VARIANT)

' // One-dimensional array of VT_BSTR with 5 elements and a lower-bound of 1
DIM dsa AS DSAFEARRAY = DSAFEARRAY(VT_BSTR, 5, 1)

Constructor (SAFEARRAYBOUND)

Creates a DSAFEARRAY from another DSAFEARRAY.

CONSTRUCTOR DSAFEARRAY (BYREF dsa AS DSAFEARRAY)

CConstructor (SAFEARRAY PTR)

Creates a DSAFEARRAY from a safe array.

CONSTRUCTOR DSAFEARRAY (BYVAL psa AS SAFEARRAY PTR)
CONSTRUCTOR DSAFEARRAY (BYVAL psa AS SAFEARRAY PTR, BYVAL fAttach AS BOOLEAN)

Constructor (VARIANT PTR)

Creates a DSAFEARRAY from a Variant of type VT_ARRAY.

CONSTRUCTOR DSAFEARRAY (BYVAL pvar AS VARIANT PTR)

Operator * (GetPtr)

Returns a pointer to the underlying safe array descriptor.

OPERATOR * () AS ANY PTR

Remark

You can also call the GetPtr method.

Operator LET ( = )

Assigns a DSAFEARRAY to another DSAFEARRAY.
Assigns a safe array to a DSAFEARRAY.
Assigns a variant of type VT_ARRAY to a DSAFEARRAY.

OPERATOR LET (BYREF dsa AS DSAFEARRAY)
OPERATOR LET (BYVAL psa AS SAFEARRAY PTR)
OPERATOR LET (BYVAL pvar AS VARIANT PTR)

AfxStrJoin

Returns a string consisting of all of the strings in an array, each separated by a delimiter. If the delimiter is a null (zero-length) string then no separators are inserted between the string sections. If the delimiter expression is the 3-byte value of “,” which may be expressed in your source code as the string literal “““,”“” or as Chr(34,44,34) then a leading and trailing double-quote is added to each string section. This ensures that the returned string contains standard comma-delimited quoted fields that can be easily parsed.

FUNCTION AfxStrJoin (BYREF dsa AS DSAFEARRAY, BYREF wszDelimiter AS WSTRING = " ") AS DWSTRING

Return value

A DWSTRING containing the joined string.

Usage example

DIM dsa AS DSAFEARRAY = DSAFEARRAY("STRING", 3, 1)
dsa.PutStr(1, "One")
dsa.PutStr(2, "Two")
dsa.PutStr(3, "Three")
DIM dws AS DWSTRING = AfxStrJoin(dsa, ",")
PRINT dws   ' ouput: One,Two,Three

AfxStrSplit

Splits a string into tokens, which are sequences of contiguous characters separated by any of the characters that are part of delimiters.

FUNCTION AfxStrSplit (BYREF wszStr AS CONST WSTRING, BYREF wszDelimiters AS WSTRING = " ") AS DSAFEARRAY

Return value

A DSAFEARRAY containing a token in each element.

Usage example

DIM dws AS DWSTRING = "- This, a sample string."
DIM dsa AS DSAFEARRAY = AfxStrSplit(dws, " ,.-")
FOR i AS LONG = dsa.LBound TO dsa.UBound
  PRINT dsa.GetStr(i)
NEXT

AccessData

Retrieves a pointer to the array data and increments the lock count of an array.

FUNCTION AccessData () AS ANY PTR

Return value

IF it succeeds, it returns a pointer to the array data. If it fails, it returns a null pointer.

Append

Appends a value to the end of the one-dimensional safe array.

FUNCTION Append (BYVAL pData AS ANY PTR) AS HRESULT
FUNCTION Append (BYREF bsData AS BSTRING) AS HRESULT
FUNCTION Append (BYREF dvData AS DVAEIANT) AS HRESULT
FUNCTION Append (BYVAL vData AS VARIANT) AS HRESULT

Appends a string to the end of the one-dimensional safe array.

FUNCTION AppendStr (BYVAL pwszData AS WSTRING PTR) AS HRESULT
FUNCTION AppendVar (BYREF dvData AS DVARIANT) AS HRESULT

Usage examples

' // Creates a one-dimensional array of doubles
'DIM dsa AS DSAFEARRAY = DSAFEARRAY(VT_R8, 2, 1)
DIM dsa AS DSAFEARRAY = DSAFEARRAY("DOUBLE", 2, 1)

DIM dblVal AS DOUBLE = 12345.12
dsa.Put(1, @dblVal)
dblVal = 74447.34
dsa.Put(2, @dblVal)
dblVal = 63535.567
dsa.Append(@dblVal)

dsa.Get(1, @dblVal)
print dblVal
dsa.Get(2, @dblVal)
print dblVal
dsa.Get(3, @dblVal)
print dblVal

' // Creates a one-dimensional array of variants
'DIM dsa AS DSAFEARRAY = DSAFEARRAY(VT_VARIANT, 2, 1)
DIM dsa AS DSAFEARRAY = DSAFEARRAY("VARIANT", 2, 1)
dsa.PutVar(1, "Test string")
dsa.PutVar(2, 12345)
dsa.AppendVar("Test string appended")

DIM dvOut AS DVARIANT
dvOut = dsa.GetVar(1)
print dvOut
dvOut = dsa.GetVar(2)
print dvOut
dvOut = dsa.GetVar(3)
print dvOut

Return value

S_OK (0) on success or an HREUSLT code on failure.

Attach

Attaches a safe array to a DSAFEARRAY object.

FUNCTION Attach (BYVAL psaSrc AS SAFEARRAY PTR) AS HRESULT

Return value

S_OK (0) on success or an HREUSLT code.

DestroyData / Clear / Erase / Reset

Destroys all the data in a safe array.

FUNCTION DestroyData () AS HRESULT

Return value

S_OK (0) on success or an HREUSLT code on failure.

Copy

Creates a copy of the safe array.

FUNCTION Copy () AS SAFEARRAY PTR

Return value

Pointer of the new array descriptor. You must free this pointer calling the API function SafeArrayDestroy.

CopyData

Copies the source array to the target array after releasing any resources in the target array. This is similar to Copy, except that the target array has to be set up by the caller. The target is not allocated or reallocated.

FUNCTION CopyData (BYVAL psaTarget AS SAFEARRAY PTR) AS HRESULT

On exit, the array referred to by psaTarget contains a copy of the data if the call succeeds.

Return value

S_OK (0) on success or an HREUSLT code.

CopyFrom

Copies the contents of the passed safe array.

FUNCTION CopyFrom (BYVAL psaSrc AS SAFEARRAY PTR) AS HRESULT

Return value

S_OK (0) on success or an HREUSLT code on failure.

Remarks

CopyFrom calls the string or variant manipulation functions if the array to copy contains either of these data types. If the array being copied contains object references, the reference counts for the objects are incremented.

CopyFromVariant

Copies the contents of a VARIANT of type VT_ARRAY to the object. The VARIANT remains unaltered.

FUNCTION CopyFromVariant (BYVAL pvar AS VARIANT PTR) AS HRESULT

pvar must be variant of type VT_ARRAY, i.e. containing a safe array. If it is of another type, an invalid data error is returned.

Return value

S_OK (0) on success or an HREUSLT code on failure.

Remarks

CopyFromVariant calls the string or variant manipulation functions if the array to copy contains either of these data types. If the array being copied contains object references, the reference counts for the objects are incremented.

CopyToVariant

Copies the safe array to the passed variant.

FUNCTION CopyToVariant (BYVAL pvar AS VARIANT PTR) AS HRESULT

pvar is a pointer to the variant where the safe array will be copied.

Return value

S_OK (0) on success or an HREUSLT code on failure.

Count

Returns the number of elements in the specified dimension of the array.

FUNCTION Count (BYVAL nDim AS UINT = 1) AS UINT

The optional nDim parameter is the array dimension for which to get the number of elements. You don’t need to pass this parameter if the safe array in one-dimensional.

Return value

S_OK (0) on success or an HREUSLT code on failure.

Create

Creates a safe array from the given VARTYPE, number of dimensions and bounds.

Multidimensional array:

FUNCTION Create (BYVAL vt AS VARTYPE, BYVAL cDims AS UINT, BYVAL prgsabound AS SAFEARRAYBOUND PTR) AS HRESULT

One-dimensional array:

FUNCTION Create (BYVAL vt AS VARTYPE, BYVAL cElements AS ULONG, BYVAL lLBound AS LONG) AS HRESULT

Two-dimensional array:

FUNCTION Create (BYVAL vt AS VARTYPE, BYVAL cElements1 AS ULONG, BYVAL lLBound1 AS LONG, _
   BYVAL cElements2 AS ULONG, BYVAL lLBound2 AS LONG) AS HRESULT

Return value

S_OK (0) on success or an HREUSLT code on failure.

CreateEx

Creates a safe array from the given VARTYPE, number of dimensions and bounds.

Multidimensional array:

FUNCTION CreateEx (BYVAL vt AS VARTYPE, BYVAL cDims AS UINT, _
   BYVAL prgsabound AS SAFEARRAYBOUND PTR, BYVAL pvExtra AS PVOID) AS HRESULT

One-dimensional array:

FUNCTION CreateEx (BYVAL vt AS VARTYPE, BYVAL cElements AS ULONG, _
   BYVAL lLBound AS LONG, BYVAL pvExtra AS PVOID) AS HRESULT

Two-dimensional array:

FUNCTION CreateEx (BYVAL vt AS VARTYPE, BYVAL cElements1 AS ULONG, BYVAL lLBound1 AS LONG, _
   BYVAL cElements2 AS ULONG, BYVAL lLBound2 AS LONG, BYVAL pvExtra AS PVOID) AS HRESULT

Return value

S_OK (0) on success or an HRESULT code on failure.

CreateVector

Creates a fixed size safe array from the given VARTYPE, lower bound and number of elements.

FUNCTION CreateVector (BYVAL vt AS VARTYPE, BYVAL cElements AS ULONG, BYVAL lLBound AS LONG) AS HRESULT

Return value

S_OK (0) on success or an HRESULT code on failure.

Remarks

CreateVector allocates a single block of memory containing a SAFEARRAY structure for a single-dimension array (24 bytes), immediately followed by the array data. All of the existing safe array functions work correctly for safe arrays that are allocated with CreateVector.

A safe array created with CreateVector is allocated as a single block of memory. Both the SafeArray descriptor and the array data block are allocated contiguously in one allocation, which speeds up array allocation. However, a user can allocate the descriptor and data area separately using the SafeArrayAllocDescriptor and SafeArrayAllocData* calls.

Usage example

DIM dsa AS DSAFEARRAY
dsa.CreateVector(VT_VARIANT, 1000, 1)
FOR i AS LONG = 1 TO 1000
   dsa.PutVar(i, "Test string " & WSTR(i))
NEXT

CreateVectorEx

Creates a fixed size safe array from the given VARTYPE, lower bound and number of elements.

FUNCTION CreateVectorEx (BYVAL vt AS VARTYPE, BYVAL cElements AS ULONG, BYVAL lLBound AS LONG, _
   BYVAL pvExtra AS ANY PTR) AS HRESULT

Return value

S_OK (0) on success or an HRESULT code on failure.

Destroy

Destroys an existing array descriptor and all of the data in the array. If objects are stored in the array, Release is called on each object in the array.

FUNCTION Destroy () AS HRESULT

Return value

S_OK (0) on success or an HRESULT code on failure.

Detach

Detaches the safe array descriptor from the DSAFEARRAY.

FUNCTION Detach () AS SAFEARRAY PTR

Return value

Returns a pointer to a SAFEARRAY descriptor.

Remarks

The caller takes ownership of it and must destroy it when no longer needed.

ElemSize

Returns the size of an element.

FUNCTION ElemSize () AS UINT

Return value

Returns the size (in bytes) of an element in a safe array. Does not include size of pointed-to data.

Features / Flags

Returns the flags used by the safe array. This is the same that the Flags method.

FUNCTION Features () AS USHORT

Find

Scans the array to search for the specified string.

FUNCTION Find (BYREF wszFind AS WSTRING, BYVAL IgnoreCase AS BOOLEAN = TRUE) AS LONG

Return value

The index of the retrieved array element, or 0 on failure.

Usage example

' // Create a one-dimensional array of strings
DIM dsa AS DSAFEARRAY = DSAFEARRAY("BSTR", 2, 1)
dsa.PutStr(1, "Test string 1")
dsa.PutStr(2, "Test string 2")
dsa.InsertStr(2, "12345.67")
DIM nPos AS LONG = dsa.Find("Test string 2")
PRINT nPos

Get / GetStr / GetVar

Retrieves a single element of the array.

Multidimensional array:

FUNCTION Get (BYVAL prgIndices AS LONG PTR, BYVAL pData AS ANY PTR) AS HRESULT
FUNCTION Get (BYVAL prgIndices AS LONG PTR, BYREF bsData AS BSTRING) AS HRESULT
FUNCTION Get (BYVAL prgIndices AS LONG PTR, BYREF dvData AS DVARIANT) AS HRESULT
FUNCTION GetStr (BYVAL prgIndices AS LONG PTR) AS BSTRING
FUNCTION GetVar (BYVAL prgIndices AS LONG PTR) AS DVARIANT

One-dimensional array:

FUNCTION Get (BYVAL idx AS LONG, BYVAL pData AS ANY PTR) AS HRESULT
FUNCTION Get (BYVAL idx AS LONG, BYREF bsData AS BSTRING) AS HRESULT
FUNCTION Get (BYVAL idx AS LONG, BYREF dvData AS DVARIANT) AS HRESULT
FUNCTION GetStr (BYVAL idx AS LONG) AS BSTRING
FUNCTION GetVar (BYVAL idx AS LONG) AS DVARIANT

Two-dimensional array:

FUNCTION Get (BYVAL cElem AS LONG, BYVAL cDim AS LONG, BYVAL pData AS ANY PTR) AS HRESULT
FUNCTION Get (BYVAL cElem AS LONG, BYVAL cDim AS LONG, BYREF bsData AS BSTRING) AS HRESULT
FUNCTION Get (BYVAL cElem AS LONG, BYVAL cDim AS LONG, BYREF dvData AS DVARIANT) AS HRESULT
FUNCTION GetStr (BYVAL cElem AS LONG, BYVAL cDim AS LONG) AS DVARIANT
FUNCTION GetVar (BYVAL cElem AS LONG, BYVAL cDim AS LONG) AS DVARIANT

First element, then dimension, e.g. 2, 1 (element 2, first dimension), 1, 2 (element 1, 2nd dimension).

Usage example

' // One-dimensional array of VT_BSTR
DIM dsa AS DSAFEARRAY = DSAFEARRAY(VT_BSTR, 2, 1)
dsa.PutStr(1, "Test string 1")
print dsa.GetStr(1)
dsa.PutStr(2, "Test string 2")
print dsa.GetStr(2)

' // One-dimensional array of VT_VARIANT
DIM dsa AS DSAFEARRAY = DSAFEARRAY(VT_VARIANT, 5, 1)
DIM dv1 AS DVARIANT = "Test variant 1"
dsa.Put(1, dv1)
DIM dvOut AS DVARIANT
dsa.Get(1, dvOut)
print dvOut
DIM dv2 AS DVARIANT = "Test variant 2"
dsa.Put(1, dv2)
dsa.Get(1, dvOut)
print dvOut

' // Two-dimensional array of BSTR
' // 2D: elements = 5, lower bound = 1
' // 2D: elements = 3, lower bound = 1
DIM rgsabounds(0 TO 1) AS SAFEARRAYBOUND = {(5, 1), (3, 1)}
DIM csa AS DSAFEARRAY = DSAFEARRAY(VT_BSTR, 2, @rgsabounds(0))

' // array index: first element, first dimension
DIM rgidx(0 TO 1) AS LONG = {1, 1}
DIM bs1 AS BSTRING = "Test string 1"
' // Put the value
dsa.Put(@rgidx(0), bs1)
' // Get the value
DIM bsOut AS BSTRING
dsa.Get(@rgidx(0), bsOut)
print bsOut
' // array index: second element, first dimension
rgidx(0) = 2 : rgidx(1) = 1
' // Put the value
DIM bs2 AS BSTRING = "Test string 2"
dsa.Put(@rgidx(0), bs2)
' // Get the value
dsa.Get(@rgidx(0), bsOut)
print bsOut

' // array index: first element, second dimension
rgidx(0) = 1 : rgidx(1) = 2
' // Put the value
DIM bs3 AS BSTRING = "Test string 3"
dsa.Put(@rgidx(0), bs3)
' // Get the value
dsa.Get(@rgidx(0), bsOut)
print bsOut

' // array index: second element, second dimension
rgidx(0) = 2 : rgidx(1) = 2
' // Put the value
DIM bs4 AS BSTRING = "Test string 4"
dsa.Put(@rgidx(0), bs4)
' // Get the value
dsa.Get(@rgidx(0), bsOut)
print bsOut

Return value (Get)

S_OK (0) on success or an HRESULT code on failure.

Return value (GetStr / GetVar)

The string or variant element.

Remarks

This method calls SafearrayLock and SafearrayUnlock automatically, before and after retrieving the element. The caller must provide a storage area of the correct size to receive the data. If the data element is a string, object, or variant, the function copies the element in the correct way.

GetIID

Returns the GUID of the interface contained within a given safe array.

FUNCTION GetIID () AS GUID

Return value

The GUID of the interface, on success, or a null guid on failure.

GetRecordInfo

Retrieves the IRecordInfo interface of a UDT contained in a given safe array.

FUNCTION GetRecordInfo () AS IRecordInfo PTR

GetType

Returns the VARTYPE stored in the given safe array.

FUNCTION GetType () AS VARTYPE

Insert

Inserts a value at the specified position of the safe array.

FUNCTION Insert (BYVAL nPos AS LONG, BYVAL pData AS ANY PTR) AS HRESULT
FUNCTION Insert (BYVAL nPos AS LONG, BYREF bsData AS BSTRING) AS HRESULT
FUNCTION Insert (BYVAL nPos AS LONG, BYREF dvData AS DVARIANT) AS HRESULT
FUNCTION Insert (BYVAL nPos AS LONG, BYVAL vData AS VARIANT) AS HRESULT

Inserts a value at the beginning of the safe array.

FUNCTION Insert (BYVAL pData AS ANY PTR) AS HRESULT
FUNCTION Insert (BYREF bsData AS BSTRING) AS HRESULT
FUNCTION Insert (BYREF dvData AS DVARIANT) AS HRESULT
FUNCTION Insert (BYVAL vData AS VARIANT) AS HRESULT

Inserts a string.

FUNCTION InsertStr (BYVAL nPos AS LONG, BYVAL pwszData AS WSTRING PTR) AS HRESULT
FUNCTION InsertStr (BYVAL pwszData AS WSTRING PTR) AS HRESULT

Inserts a variant.

FUNCTION InsertVar (BYVAL nPos AS LONG, BYREF dvData AS DVARIANT) AS HRESULT
FUNCTION InsertVar (BYREF dvData AS DVARIANT) AS HRESULT

Return value

S_OK (0) on success or an HRESULT code on failure.

Usage example

' // Create a one-dimensional array of variants
'DIM dsa AS DSAFEARRAY = DSAFEARRAY(VT_VARIANT, 2, 1)
DIM dsa AS DSAFEARRAY = DSAFEARRAY("VARIANT", 2, 1)

dsa.PutVar(1, "Test string 1")
dsa.PutVar(2, "Test string 2")
dsa.InsertVar(2, 12345.67)

DIM dvOut AS DVARIANT
dsa.Get(1, dvOut)
print dvOut
dsa.Get(2, dvOut)
print dvOut
dsa.Get(3, dvOut)
print dvOut

IsResizable

Tests if the safe array can be resized.

FUNCTION IsResizable () AS BOOLEAN

Return value

TRUE if the array can be resized; FALSE, otherwise.

LBound

Returns the lower bound for any dimension of a safe array.

FUNCTION LBound (BYVAL nDim AS UINT = 1) AS LONG

UBound

Returns the upper bound for any dimension of a safe array.

FUNCTION UBound (BYVAL nDim AS UINT = 1) AS LONG

LocksCount

Returns the number of times the array has been locked without the corresponding unlock.

FUNCTION LocksCount () AS UINT

MoveFromVariant

Transfers ownership of the safe array contained in the variant parameter to this object. The variant is then changed to VT_EMPTY.

FUNCTION MoveFromVariant (BYVAL pvar AS VARIANT PTR) AS HRESULT

Return value

S_OK (0) on success or an HRESULT code on failure.

MoveToVariant

Transfers ownership of the safe array to a variant and detaches it from the class.

FUNCTION MoveToVariant (BYVAL pvar AS VARIANT PTR) AS HRESULT

Usage example

' // One-dimensional array of VT_BSTR
DIM dsa AS DSAFEARRAY = DSAFEARRAY(VT_BSTR, 2, 1)
dsa.PutStr(1, BSTRING("Test string 1"))
DIM bsOut AS BSTRING
bsout = dsa.GetStr(1)
print bsOut
dsa.PutStr(2, BSTRING("Test string 2"))
bsOut = dsa.GetStr(2)
print bsOut

DIM v AS VARIANT
dsa.MoveToVariant(@v)
print AfxVarToStr(@v)
VariantClear @v

Return value

S_OK (0) on success or an HRESULT code on failure.

NumDims

Returns the number of dimensions in the array.

FUNCTION NumDims () AS UINT

PtrOfIndex

Returns a pointer to an array element.

Multidimensional array:

FUNCTION PtrOfIndex (BYVAL prgIndices AS LONG PTR) AS ANY PTR

One-dimensional array:

FUNCTION PtrOfIndex (BYVAL idx AS LONG) AS HRESULT

Two-dimensional array:

FUNCTION PtrOfIndex (BYVAL cElem AS LONG, BYVAL cDim AS LONG) AS HRESULT

Put

Stores the data element at a given location in the array.

Multidimensional array:

FUNCTION Put (BYVAL prgIndices AS LONG PTR, BYVAL pData AS ANY PTR) AS HRESULT
FUNCTION PutStr (BYVAL prgIndices AS LONG PTR, BYREF bsData AS BSTRING) AS HRESULT
FUNCTION PutVar (BYVAL prgIndices AS LONG PTR, BYREF dvData AS DVARIANT) AS HRESULT

One-dimensional array:

FUNCTION Put (BYVAL idx AS LONG, BYVAL pData AS ANY PTR) AS HRESULT
FUNCTION PutStr (BYVAL idx AS LONG, BYREF bsData AS BSTRING) AS HRESULT
FUNCTION PutVar (BYVAL idx AS LONG, BYREF dvData AS DVARIANT) AS HRESULT

Two-dimensional array:

FUNCTION Put (BYVAL cElem AS LONG, BYVAL cDim AS LONG, BYVAL pData AS ANY PTR) AS HRESULT
FUNCTION PutStr (BYVAL cElem AS LONG, BYVAL cDim AS LONG, BYREF bsData AS BSTRING) AS HRESULT
FUNCTION PutVar (BYVAL cElem AS LONG, BYVAL cDim AS LONG, BYREF dvData AS DVARIANT) AS HRESULT

Return value

S_OK (0) on success or an HRESULT code on failure.

Remarks

This function automatically calls SAfeArrayLock and SafeArrayUnlock before and after assigning the element. If the data element is a string, object, or variant, the function copies it correctly when the safe array is destroyed. If the existing element is a string, object, or variant, it is cleared correctly. If the data element is a VT_DISPATCH or VT_UNKNOWN, AddRef is called to increment the object’s reference count.

Multiple locks can be on an array. Elements can be put into an array while the array is locked by other operations.

Redim

Changes the right-most (least significant) bound of a safe array.

Multidimensional array:

FUNCTION Redim (BYVAL pnewsabounds AS SAFEARRAYBOUND PTR) AS HRESULT

One-dimensional array:

FUNCTION Redim (BYVAL cElements AS ULONG, BYVAL lLBound AS LONG) AS HRESULT

Two-dimensional array:

FUNCTION Redim (BYVAL cElements1 AS ULONG, BYVAL lLBound1 AS LONG, _
   BYVAL cElements2 AS ULONG, BYVAL lLBound2 AS LONG) AS HRESULT

Usage example

' // One-dimensional array of VT_VARIANT
' // Two elements, lower-bound 1
'DIM dsa AS DSAFEARRAY = DSAFEARRAY(VT_VARIANT, 2, 1)
DIM dsa AS DSAFEARRAY = DSAFEARRAY("VARIANT", 2, 1)
DIM dv1 AS DVARIANT = "Test variant 1"
dsa.PutVar(1, dv1)
DIM dvOut AS DVARIANT
dvOut = dsa.GetVar(1)
print dvOut

DIM dv2 AS DVARIANT = "Test variant 2"
dsa.PutVar(1, dv2)
dvOut = dsa.GetVar(1)
print dvOut

' // Redim (preserve) the safe array
dsa.Redim(1, 3)
DIM dv3 AS DVARIANT = "Test variant 3"
dsa.PutVar(3, dv3)
dvOut = dsa.GetVar(3)
print dvOut

Return value

S_OK (0) on success or an HRESULT code on failure.

Remove

Removes the specified array element.

FUNCTION Remove (BYVAL nPos AS LONG) AS HRESULT
FUNCTION RemoveStr (BYVAL nPos AS LONG) AS HRESULT
FUNCTION RemoveVar (BYVAL nPos AS LONG) AS HRESULT

Return value

S_OK (0) on success or an HRESULT code on failure.

SetIID

Sets the IID (a GUID) of the interface contained within a given safe array.

FUNCTION SetIID (BYVAL pguid AS GUID PTR) AS HRESULT

Return value

S_OK (0) on success or an HRESULT code on failure.

SetRecordInfo

Sets the IRecordInfo interface of the UDT contained in a given safe array.

FUNCTION SetRecordInfo (BYVAL prinfo AS IRecordInfo PTR) AS HRESULT

Return value

S_OK (0) on success or an HRESULT code on failure.

Sort

Sorts a one-dimensional VT_BSTR DSAFEARRAY calling the C qsort function.

FUNCTION Sort (BYVAL bAscend AS BOOLEAN = TRUE) AS HRESULT

Return value

S_OK (0) on success or an HRESULT code on failure.

Usage example

' // Create a one-dimensional array of BSTR
DIM bsVal AS BSTRING = "bcde"
dsa.PutStr(1, bsVal)
bsVal = "abc"
dsa.PutStr(2, bsVal)
bsVal = "abcfg"
dsa.PutStr(3, bsVal)
' // Sort the safe array
dsa.Sort

bsVal = dsa.GetStr(1)
print bsVal
bsVal = dsa.GetStr(2)
print bsVal
bsVal = dsa.GetStr(3)
print bsVal

UnaccessData

Decrements the lock count of an array, and invalidates the pointer retrieved by AccessData.

FUNCTION UnaccessData () AS HRESULT

Return value

S_OK (0) on success or an HRESULT code on failure.